Terminal Package

PTY-based terminal emulation with multi-client support

Overview

The terminal package provides a shared terminal session using PTY (pseudo-terminal) with VT10x emulation. Multiple clients can connect to the same terminal and see synchronized output.

Type

Terminal

Wraps a PTY with VT10x terminal emulation and subscriber management.

type Terminal struct {
    vt   vt10x.Terminal
    ptmx *os.File
    cmd  *exec.Cmd
    mu   sync.Mutex
    
    width   int
    height  int
    workDir string
    
    subscribers map[chan struct{}]struct{}
    subMu       sync.RWMutex
    closed      bool
    
    lastRender string
    dirty      bool
}

Functions

New

Creates a new terminal instance.

func New(width, height int, workDir string) *Terminal

width · int · required

Terminal width in columns (defaults to 80 if < 1)

height · int · required

Terminal height in rows (defaults to 24 if < 1)

workDir · string · required

Working directory for shell (defaults to “/app” if empty)

Example:

term := terminal.New(120, 30, "/app/workspaces/my-project")

Start

Starts the shell process and begins reading output.

func (t *Terminal) Start() error

Returns: Error if PTY creation or shell start fails

Behavior:

• Creates VT10x terminal emulator
• Spawns shell process (respects $SHELL env var, defaults to /bin/sh)
• Sets environment: TERM=xterm-256color
• Starts background read loop

Example:

term := terminal.New(80, 24, "/app")
if err := term.Start(); err != nil {
    log.Fatal(err)
}

Write

Sends input to the terminal (keyboard input, etc.).

func (t *Terminal) Write(data []byte) (int, error)

data · []byte · required

Raw input data to send to PTY

Returns: Bytes written and error

Example:

// Send "ls" command
term.Write([]byte("ls\r"))

// Send Ctrl+C
term.Write([]byte{0x03})

Render

Renders the current terminal state to a string with ANSI codes.

func (t *Terminal) Render() string

Returns: Rendered terminal output with colors and formatting

Features:

• Caching: Returns cached render if terminal hasn’t changed
• Colors: Full 256-color ANSI support
• Cursor: Visual cursor using reverse video effect
• Optimization: Run-length encoding for color sequences

Example:

output := term.Render()
fmt.Print(output)

Resize

Resizes the terminal dimensions.

func (t *Terminal) Resize(width, height int)

width · int · required

New width in columns

height · int · required

New height in rows

Behavior:

• Updates VT10x emulator size
• Sends SIGWINCH via pty.Setsize()
• Invalidates render cache

Close

Closes the terminal and cleans up resources.

func (t *Terminal) Close() error

Cleanup:

• Closes all subscriber channels
• Closes PTY file descriptor
• Kills shell process

Size

Returns current terminal dimensions.

func (t *Terminal) Size() (width, height int)

Subscription Pattern

The terminal supports multi-client subscriptions for real-time updates.

Subscribe

Creates a channel for receiving update notifications.

func (t *Terminal) Subscribe() chan struct{}

Returns: Channel that receives a signal on each terminal update

Example:

updates := term.Subscribe()
defer term.Unsubscribe(updates)

for range updates {
    output := term.Render()
    updateUI(output)
}

Unsubscribe

Removes a subscription channel.

func (t *Terminal) Unsubscribe(ch chan struct{})

ch · chan struct{} · required

Channel returned by Subscribe()

Implementation Details

Read Loop

The background readLoop() goroutine:

1. Reads from PTY (4KB buffer)
2. Writes to VT10x emulator
3. Marks terminal as dirty
4. Broadcasts to all subscribers
5. Exits when shell process terminates

Render Optimization

// Return cached render if not dirty
if !t.dirty && t.lastRender != "" {
    return t.lastRender
}

The terminal caches renders and only re-renders when content changes, reducing CPU usage for idle terminals.

Color Mapping

func fgColor(c vt10x.Color) string
func bgColor(c vt10x.Color) string

Maps VT10x colors to ANSI escape codes:

• Colors 0-7: Standard ANSI (30-37, 40-47)
• Colors 8-15: Bright ANSI (90-97, 100-107)
• Colors 16-255: Extended palette (38;5;n, 48;5;n)

Thread Safety

All public methods are thread-safe:

• mu sync.Mutex protects terminal state
• subMu sync.RWMutex protects subscriber map